docs(spec): name the mis-aimed group case in navigationContributions[].group - #16508

Fixes #14925

The describe() on navigationContributions[].group was true and incomplete: it documented the omitted case and said nothing about group being present and naming no group the target app declares — the case that actually bites, because the contributing package cannot see the target app's group ids at authoring time (the target app belongs to another package). A wrong id is undetectable from the contributor's own source, and the platform relocates the items to the app top level rather than refusing them, so the menu renders, a smoke test passes, and the information architecture has silently changed.

The line, located by symbol

Re-located by symbol as instructed rather than trusted from the card: NavigationContributionSchema's group property in packages/spec/src/ui/app.zod.ts. It is still at :764 — the anchor had not drifted.

Final wording

'Target group nav-item id to append into (e.g. "group_integrations"); omit to append at
 the app top level. Naming a group the target app does not declare is not refused: the
 items are appended at the app top level anyway and a `nav_contribution_group_missing`
 diagnostic is emitted — by the runtime at `warn`, and by `os build` and `os validate`
 at compile time.'

Four decisions behind it:

• "is not refused" leads, because the surprise is the absence of a refusal, not the presence of a diagnostic.
• The diagnostic code is spelled in full, so an author who sees nav_contribution_group_missing in build output can search back to the key that produced it.
• Both commands are named. Naming only os build would have been wrong against what shipped — see below.
• No pipe characters. This string renders into two markdown table cells; a | would break both rows.

Verification of the two corrections in comment 5525508353 — checked against the tree, not inherited

① os validate reports the diagnostic too. CONFIRMED. findNavGroupDiagnostics has exactly two non-test call sites, and they are the two commands: packages/cli/src/commands/compile.ts:49 and packages/cli/src/commands/validate.ts:43. Each folds the result into its own warnings list — compile.ts:202, validate.ts:148 — rather than into a key of its own. validate.ts:130 carries the reason in-source: the residue pin "asserts that nothing rides in build's warnings that validate does not also report".

② A top-level navigationGroupDiagnostics key does not exist. CONFIRMED. git grep navigationGroupDiagnostics returns exactly one hit repo-wide, and it is prose, not code: packages/cli/src/utils/nav-contribution-groups.ts:46, in a doc block explaining that the first cut carried such a key and that two standing pins (build-json-advisory-parity.e2e.test.ts, build-json-undeclared-key-parity.e2e.test.ts, both present in packages/cli/test/) rejected it. No schema, no payload, no emitter. Nothing here describes it.

Regeneration — the command, and the count actually measured

pnpm --filter @objectstack/spec gen:schema     # exit 0
pnpm --filter @objectstack/spec gen:docs       # exit 0 — "Generated 228 files"

⛔ No generated artifact was hand-edited.

Measured, not repeated from the card. The card estimated "~14 artifacts"; the measurement says 26 carriers, and they split in a way worth stating because only one half is reviewable in this diff:

The 24 that are not in the diff are the packages/spec/json-schema/ tree, which .gitignore:63 excludes — built on demand, not committed. They are 12 json-schema/api/*.json and 10 json-schema/kernel/*.json package envelopes, the bundled json-schema/objectstack.json, and json-schema/ui/NavigationContribution.json itself. So the card's "~11 api envelopes" undercounted, and its list omitted the kernel/ envelopes entirely.

The two tracked files are content/docs/references/ui/app.mdx and content/docs/references/kernel/manifest.mdx, one table row each.

Clause ② reads NO — confirmed mechanically, and the gate was proved able to say otherwise

Prose on an existing key. group is still SnakeCaseIdentifierSchema.optional(); nothing is refused that was not refused before.

• pnpm --filter @objectstack/spec check:api-surface — exit 0, verdict line: @objectstack/spec public API surface + factory signatures unchanged ✓
• pnpm --filter @objectstack/spec check:authorable-surface — exit 0, and authorable-surface.json plus json-schema.manifest.json are byte-identical to base (the regeneration left them untouched; only the two .mdx files appear in git status).

A silent green is not a reading, so the second gate was ablated at the committed state to show it can go red on exactly this axis. One new authorable key injected into the same schema (groupFallback), proved on disk (injected-text count 1, git hash-object differing from the HEAD blob), produced:

❌ authorable-surface/ is out of date (1 key(s) not recorded).      exit 1

Restored with git checkout HEAD -- packages/spec/src/ui/app.zod.ts, proved by an empty git diff HEAD, and the gitignored schema tree regenerated afterwards so no probe residue survives (grep -rl "ABLATION PROBE" packages/spec/json-schema/ returns nothing, while the real sentence still returns its 24 files — the positive control for that zero).

Gates and tests

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (change set: 4 paths vs merge base 21c5dcbb3) — 90 commands, 89 green. Every exit code captured before any pipe.

• pnpm --filter '@objectstack/spec...' build — exit 0 (check-dts-emitted: 34/34)
• pnpm --filter @objectstack/spec typecheck — exit 0
• pnpm --filter @objectstack/spec test — exit 0, 482 files / 13102 tests passed
• check:docs — exit 0, 228 generated files in sync with packages/spec. Ablated too: reverting only the two regenerated .mdx files to base makes it exit 1, naming both files "out of date" — so its green here is a measurement of this regeneration and not of an untested gate.
• Five gates first returned PREREQUISITE NOT MET for unbuilt packages, which is NOT MEASURED rather than red. Four were cleared by building @objectstack/lint, @objectstack/formula, @objectstack/client, @objectstack/client-react and re-running: check:doc-formula-expressions, check:doc-security-posture, check:skill-examples, check:docs-transcript-drift — all exit 0.
• One declared narrowing: pnpm check:dual-build-cjs-loads needs a full-repo dist/ (it named 86 unbuilt packages) and stays NOT MEASURED here — a whole-workspace build does not fit this container's foreground budget. It reads emitted CJS loadability; this diff is one string literal inside a .describe(), two generated markdown table rows and a changeset, and moves no package's exports map or build shape. Left to CI.

Verdicts, logs and the two ablation transcripts are in the report comment on #14925.

Changeset

.changeset/nav-contribution-group-mis-aim-describe.md, @objectstack/spec: patch. Patch is the level: the published JSON Schema description for an existing key changes and the generated reference rows change, so it is user-visible and needs an entry — but no key is added or removed, no type moves, and no runtime behaviour changes, which is what would have made it minor.

Out of scope

• Filed docs(source): two source comments about a mis-aimed navigationContributions[].group are incomplete against what #14920 shipped #16507: two source comments carrying the same incompleteness — the NavigationContributionSchema JSDoc just above this key still names only the omitted case, and examples/app-multi-package/src/packages/orders/index.ts:47 still names only os build. Neither reaches a generated artifact (verified by git grep), and the example lives in another package, so folding them in would widen this PR past the regeneration family it was sized for.
• decision(objectql): a navigationContributions[].group that names no group in the target app is silently RELOCATED to the top level — refuse, warn, or leave to the consumer? #14553 is not addressed here and remains open on its own terms. The diagnostic itself is fix(objectql,cli): a navigation contribution relocated past a missing group now says so, at warn and at build time #14920, already landed and untouched.

Generated by Claude Code